ShippingOptions API
ShippingOptions Overview
Overview
The ShippingOptions API is a GET API that returns the shipping options and rates available depending on customer pick up and destination addresses and parcel dimensions and weight. There are two endpoints, one for international destination addresses and one for domestic destination addresses.
ShippingOptions includes the following resources:
| Name | Function | Verb |
|---|---|---|
| Domestic | Retrieves shipping option information for a domestic delivery address | GET |
| International | Retrieves shipping option information for an international delivery address | GET |
Operational Considerations
The following information is intended to inform integrating merchants of NZ Post Group operational processes that may impact how the ShippingOptions API is used.
- Dimensions of parcels need to be accurate for accurate pricing to display, however we know this can be a challenge when packing multiple items together in a parcel. If a default or zero dimension is used, the price will be a default also. To determine a default size for your packages, speak to your NZ Post business manager who can advise you on the best options for your shipping profile.
- Note that the ShippingOptions API provides two shipping options services, one for New Zealand delivery addresses and one for international delivery addresses. If you expect your application to be used for searching for shipping options both in New Zealand and overseas, your user interface should capture the country prior to calling the service so that your application's logic can determine which service to invoke.
- If your business is using the API pricing data for reconciliation of your invoices and margins - it is recommended to use accurate parcel dimensions wherever possible.
- Some parcel sizes are weighed and measured within the CourierPost operational network. Where the parcel label information does not match the actual weight or measurements, and the actual weight or measurements incurs a higher charge, the difference will be invoiced with an administration fee. Find out more here.
- Prices returned from the API for Pace and CourierPost exclude VFR (Variable Fuel Rate) which is stated at parcel invoicing. For information on VFR for both Pace and CourierPost, please go here.
- As a merchant, you control the delivery prices displayed to your customers. You may calculate the displayed price based on information provided by the ShippingOptions API. If this is the case, you should include logic to display default delivery prices in the event that the ShippingOptions API is temporarily unavailable to ensure that your customer's experience is not affected.